Avorion Script API Documentation

Player [Server] Player

Properties
alliance
allianceIndex
craft
craftFaction
craftIndex
group
id
loggingOut
maxBuildableMaterial
maxBuildableSockets
maxNumMails
maxNumShips
maxNumStations
numCrafts
numMails
numShips
numStations
ownsBehemothDLC
ownsBlackMarketDLC
ownsIntoTheRiftDLC
playtime
alwaysAtWar
baseName
fullLogId
homeSectorUnknown
index
infiniteResources
initialRelations
initialRelationsToPlayer
isAIFaction
isAlliance
isPlayer
money
name
stateForm
staticRelationsToAI
staticRelationsToAll
staticRelationsToPlayers
unformattedName

Member Functions
activateUsableItem
addKnownSector
addMail
addScript
addScriptOnce
callbacksRegistered
clearMail
createCraftFromShipInfo
getKnownSector
getKnownSectorCoordinates
getKnownSectors
getKnownSectorsOfFaction
getMail
getMailsById
getNamesOfShipsInSector
getReconstructionSiteCoordinates
getRespawnSiteCoordinates
getScripts
getSectorCoordinates
getShipAvailability
getShipBoundingBox
getShipCanPassRifts
getShipCargo
getShipCargos
getShipCrew
getShipDestroyed
getShipHyperspaceReach
getShipIcon
getShipNames
getShipOrderInfo
getShipPayment
getShipPaymentTime
getShipPlan
getShipPosition
getShipReconstructionValue
getShipStatus
getShipSystems
getShipTurretDesigns
getShipType
hasScript
invokeFunction
knowsSector
ownsShip
readMail
registerCallback
removeDestroyedShipInfo
removeKnownSector
removeMail
removeScript
resetHyperspaceCalculation
resolveScriptPath
restoreCraft
restoreTurrets
sendCallback
sendChatMessage
setReconstructionSiteCoordinates
setRespawnSiteCoordinates
setSectorCoordinates
setShipAvailability
setShipDestroyed
setShipIcon
setShipOrderInfo
setShipReconstructionValue
unregisterCallback
updateKnownSector
updateKnownSectorPreserveNote
updateMail
addPlanStyle
canPay
canPayMoney
canPayResource
clearValues
getAllRelations
getHomeSectorCoordinates
getInventory
getLanguage
getPlanStyle
getPlanStyleNames
getRelation
getRelations
getRelationStatus
getResources
getTrait
getTraits
getValue
getValues
hasStaticRelationsToFaction
knowsFaction
pay
payResource
payWithoutNotify
receive
receiveResource
receiveWithoutNotify
sendCallback
sendChatMessage
setHomeSectorCoordinates
setLanguage
setResources
setStaticRelationsToFaction
setTrait
setValue

Player [Server] : Faction [Server]

This object is only available on the server.

function Player(var index)

Returns

A new instance of Player

property Alliance alliance[read-only]
property var allianceIndex[read-only]
property Entity craft
property UserObject craftFaction
returns the player's ship's faction (ie. their alliance or themselves). If the player is not in a craft, returns the player.
property Uuid craftIndex
property Group group[read-only]
property Uuid id[read-only]
property bool loggingOut[read-only]
property Material maxBuildableMaterial
property int maxBuildableSockets
property unsigned int maxNumMails[read-only]
property var maxNumShips[read-only]
property var maxNumStations[read-only]
property unsigned int numCrafts[read-only]
property unsigned int numMails[read-only]
property int numShips[read-only]
property int numStations[read-only]
property bool ownsBehemothDLC[read-only]
property bool ownsBlackMarketDLC[read-only]
property bool ownsIntoTheRiftDLC[read-only]
property unsigned int playtime[read-only]
property bool alwaysAtWar
property string baseName
property string fullLogId[read-only]
property bool homeSectorUnknown
property int index[read-only]
property bool infiniteResources
property int initialRelations
Note: AIFactions only
property int initialRelationsToPlayer
Note: AIFactions only
property bool isAIFaction[read-only]
property bool isAlliance[read-only]
property bool isPlayer[read-only]
property int money
property string name[read-only]
property string stateForm
property bool staticRelationsToAI
property bool staticRelationsToAll
property bool staticRelationsToPlayers
property Format unformattedName[read-only]

function int activateUsableItem(int index)

Activates a UsableItem from the player's inventory.

Parameters

index The index of the item in the inventory

Returns

Returns a number indicating if the call succeeded:
0 The item was successfully activated.
1 The item responded that it can't be activated right now.
2 The item wasn't found or it is no UsableInventoryItem.

function var addKnownSector(SectorView view)

Returns

nothing

function unsigned int addMail(Mail mail)

function var addScript()

function var addScriptOnce()

function int callbacksRegistered(string callbackName, var functionName)

Check how many functions are registered to a callback from the current script VM.

Parameters

callbackName The name of the callback
functionName The name of the function for which to check. If nil, will count all functions that are registered to this callback.

Returns

The amount of functions registered to the callback. -1 if an error occurred

function var clearMail(unsigned int index)

Returns

nothing

function Entity createCraftFromShipInfo(string name, Matrix position, var faction)

function SectorView getKnownSector(int x, int y)

function ivec2... getKnownSectorCoordinates()

function SectorView... getKnownSectors()

function SectorView... getKnownSectorsOfFaction(int factionIndex)

function Mail getMail(unsigned int index)

function Mail... getMailsById(string id)

function string... getNamesOfShipsInSector(int x, int y)

function int, int getReconstructionSiteCoordinates()

function int, int getRespawnSiteCoordinates()

function table<int, string> getScripts()

function Coordinates getSectorCoordinates()

function var getShipAvailability(string name)

function Box getShipBoundingBox(string name)

function bool getShipCanPassRifts(string name)

function string getShipCargo(string name)

function table<TradingGood, int> getShipCargos(string name)

function Crew getShipCrew(string name)

function var getShipDestroyed(string name)

function float getShipHyperspaceReach(string name)

function string getShipIcon(string name)

function string... getShipNames()

function var getShipOrderInfo(string name)

function float getShipPayment(string name)

function float getShipPaymentTime(string name)

function BlockPlan getShipPlan(string name)

function var... getShipPosition(string name)

function double getShipReconstructionValue(string name)

function string getShipStatus(string name)

function pair... getShipSystems(string name)

function table<int, TurretDesign> getShipTurretDesigns(string name)

function int getShipType(string name)

function var hasScript(string name)

function var... invokeFunction(var scriptName, string functionName, var... arguments)

Invokes a function in a script of the player. Use this function to invoke functions from one script in another script. The first return value of the function is an integer indicating whether or not the call was successful. When it was, this integer is followed by the return values of the invoked function.

Parameters

scriptName The name or index of the script containing the function
functionName The name of the function that will be executed
arguments An arbitrary list of arguments that will be given to the invoked function

Returns

Returns at least 1 value indicating if the call succeeded:
0 The call was successful. In this case, the return values of the script are returned in addition to the call result, following the call result.
3 The call failed because the given script was not found
4 The call failed because the given function was not found in the script
5 The call failed because the script's state has errors and is invalid

function bool knowsSector(int x, int y)

function bool ownsShip(string name)

function var readMail(unsigned int index)

Returns

nothing

function int registerCallback(string callbackName, string functionName)

Register a callback in a player. The callback may arrive with a delay. Double registration of callbacks doesn't work. When the same callback to the same callback of the same script instance is registered twice, it will still only be called once.

Parameters

callbackName The name of the callback
functionName The name of the function that will be executed in the script when the callback happens

Returns

0 on success, 1 if the registration failed

function var removeDestroyedShipInfo(string name)

Returns

nothing

function var removeKnownSector(int x, int y)

Returns

nothing

function var removeMail(unsigned int index)

Returns

nothing

function var removeScript(var script)

Returns

nothing

function var resetHyperspaceCalculation()

Returns

nothing

function var resolveScriptPath(string path)

function Entity restoreCraft(string name, Matrix position, bool withMalus)

function var restoreTurrets(Entity scriptCraft)

Returns

nothing

function var sendCallback()

Returns

nothing

function var sendChatMessage(var sender, int messageType, string message, PluralForm... args)

Send a chat message to the player. Supports sending of format arguments so that the message can be translated on the client.

Parameters

sender The sender that will be displayed for the chat message
messageType The type of chat message, 0 = Normal, 1 = Error, 2 = Warning, 3 = Info
message The message that will be sent
args The format arguments that will be sent

Returns

nothing

function var setReconstructionSiteCoordinates(int x, int y)

Returns

nothing

function var setRespawnSiteCoordinates(int x, int y)

Returns

nothing

function var setSectorCoordinates(int x, int y)

Returns

nothing

function var setShipAvailability(string name, ShipAvailability availability)

Returns

nothing

function var setShipDestroyed(string name, bool destroyed)

Returns

nothing

function var setShipIcon(string name, string icon)

Returns

nothing

function var setShipOrderInfo(string name, var value)

Returns

nothing

function var setShipReconstructionValue(string name, double value)

Returns

nothing

function int unregisterCallback(string callbackName, string functionName)

function var updateKnownSector(SectorView view)

Returns

nothing

function var updateKnownSectorPreserveNote(SectorView newView)

Returns

nothing

function var updateMail(Mail mail, unsigned int index)

Returns

nothing

function var addPlanStyle(string name, PlanStyle style)

Inherited from Faction [Server]

Returns

nothing

function bool, string, table<int, string> canPay()

Inherited from Faction [Server]

function bool, string, table<int, string> canPayMoney(int money)

Inherited from Faction [Server]

function bool, string, table<int, string> canPayResource(Material material, int amount)

Inherited from Faction [Server]

function var clearValues()

Removes all custom values of the object Inherited from Faction [Server]

Returns

nothing

function Relation... getAllRelations()

Inherited from Faction [Server]

function int, int getHomeSectorCoordinates()

Inherited from Faction [Server]

function Inventory getInventory()

Inherited from Faction [Server]

function Language getLanguage()

Inherited from Faction [Server]

function PlanStyle getPlanStyle(string name)

Inherited from Faction [Server]

function string... getPlanStyleNames()

Inherited from Faction [Server]

function Relation getRelation(int otherFactionIndex)

Inherited from Faction [Server]

function int getRelations(int factionIndex)

Inherited from Faction [Server]

function int getRelationStatus(int factionIndex)

Inherited from Faction [Server]

function int... getResources()

Inherited from Faction [Server]

function float getTrait(string trait)

Retrieves a trait value associated with a key Inherited from Faction [Server]

Parameters

trait The name of the trait

Returns

The trait value associated with the key

function table<string, float> getTraits()

Retrieves all key-value trait pairs of the faction Inherited from Faction [Server]

Returns

A table containing all custom key-value pairs

function var getValue(string key)

Retrieves a custom value saved in the entity with the given key Inherited from Faction [Server]

Parameters

key A string that serves as the name of the value

Returns

The value if the key exists, otherwise nil

function table<string, var> getValues()

Retrieves all key-value pairs of custom values Inherited from Faction [Server]

Returns

A table containing all custom key-value pairs

function bool hasStaticRelationsToFaction(int factionIndex)

Inherited from Faction [Server]

function bool knowsFaction(int factionIndex)

Inherited from Faction [Server]

function var pay(string or Format [optional] description, int money, int... resources)

Makes the faction pay a certain amount of money and resources. If the faction can't pay, the respective money and resources will be set to 0. This function accepts an optional string for Format as first argument, as an economy notification describing the transaction that will be sent to the player, in case the faction is a player.
To ease handling of transaction descriptions, the format description (if set) will receive all the remaining arguments given to the pay() function as format arguments, in the same order as they are given to the function. Dots for easier reading will be inserted as well. Examples:

faction:pay("Paid %1% Credits and %2% iron.", 50000, 250)
-> "Paid 50.000 Credits and 250 iron."

faction:pay(Format("%1% paid %2% Credits and %3% iron.", "Excelsior"), 50, 25000)
-> "Excelsior paid 50 Credits and 25.000 iron."

Inherited from Faction [Server]

Parameters

description [optional] A description for the transaction. Can either be a string or a Format. If this variable is set, money and resources will be appended to the end of the list of arguments passed to the description format string.
money Money that will be removed from the faction
resources A list of resources, starting with iron, that will be removed from the faction

Returns

nothing

function var payResource(string or Format description, Material material, int amount)

Makes the faction pay a certain amount of resources. If the faction can't pay, the respective resource will be set to 0. This function accepts a string for Format as first argument, as an economy notification describing the transaction that will be sent to the player, in case the faction is a player. Inherited from Faction [Server]

Parameters

description A description for the transaction. Can either be a string or a Format.
material The kind of material that will be removed from the faction
amount Amount that will be removed from the faction

Returns

nothing

function var payWithoutNotify(string or Format description, int money, int... args)

Similar behavior to pay(), except there will not be a notification popping up in case the faction is a player, and the description for the transaction in this function isn't optional. Inherited from Faction [Server]

Parameters

description A description for the transaction. Can either be a string or a Format. Money and resources will be appended to the end of the list of arguments passed to the description format string.
money Money that will be removed from the faction
args A list of resources, starting with iron, that will be removed from the faction

Returns

nothing

function var receive(string or Format [optional] description, int money, int... resources)

Makes the faction receive a certain amount of money and resources. This function accepts an optional string for Format as first argument, as an economy notification describing the transaction that will be sent to the player, in case the faction is a player.
To ease handling of transaction descriptions, the format description (if set) will receive all the remaining arguments given to the receive() function as format arguments, in the same order as they are given to the function. Dots for easier reading will be inserted as well. Examples:

faction:receive("Got %1% Credits and %2% iron.", 50000, 250)
-> "Got 50.000 Credits and 250 iron."

faction:receive(Format("%1% received %2% Credits and %3% iron.", "Excelsior"), 50, 25000)
-> "Excelsior received 50 Credits and 25.000 iron."

Inherited from Faction [Server]

Parameters

description [optional] A description for the transaction. Can either be a string or a Format. If this variable is set, money and resources will be appended to the end of the list of arguments passed to the description format string.
money Money that will be given to the faction
resources A list of resources, starting with iron, that will be given to the faction

Returns

nothing

function var receiveResource(string or Format description, Material material, int amount)

Makes the faction receive a certain amount of resources. This function accepts a string for Format as first argument, as an economy notification describing the transaction that will be sent to the player, in case the faction is a player. Inherited from Faction [Server]

Parameters

description A description for the transaction. Can either be a string or a Format.
material The kind of material that will be given to the faction
amount Amount that will be given to the faction

Returns

nothing

function var receiveWithoutNotify(string or Format description, int money, int... args)

Similar behavior to receive(), except there will not be a notification popping up in case the faction is a player, and the description for the transaction in this function isn't optional. Inherited from Faction [Server]

Parameters

description A description for the transaction. Can either be a string or a Format. Money and resources will be appended to the end of the list of arguments passed to the description format string.
money Money that will be given to the faction
args A list of resources, starting with iron, that will be given to the faction

Returns

nothing

function var sendCallback()

Inherited from Faction [Server]

Returns

nothing

function var sendChatMessage()

Inherited from Faction [Server]

Returns

nothing

function var setHomeSectorCoordinates(int x, int y)

Inherited from Faction [Server]

Returns

nothing

function var setLanguage(Language language)

Inherited from Faction [Server]

Returns

nothing

function var setResources()

Inherited from Faction [Server]

Returns

nothing

function var setStaticRelationsToFaction(int factionIndex, bool in)

Inherited from Faction [Server]

Returns

nothing

function var setTrait(string trait, float value)

Sets a trait value associated with a key Inherited from Faction [Server]

Parameters

trait The name of the trait
value The value of the trait, should be between -1 and 1

Returns

nothing

function var setValue(string key, var value)

Sets a custom value Inherited from Faction [Server]

Parameters

key A string that serves as the name of the value
value The value to save. Must be bool, number, string or nil. If nil is given, the value will be deleted.

Overview
Home Functions Search
Search:

This is the official documentation for the scripting API of Avorion. This documentation is automatically generated and not necessarily complete. Depending on the context in which functions exist, some documentation such as descriptions, return values or variable names or types may be missing.

Work in Progress. Documentation of Avorion Version: 2.5.7 c8e4beec84f7